feat(orchestration-v2): add subagent observability data model (1/5) by shivamhwp · Pull Request #4779 · pingdotgg/t3code

shivamhwp · 2026-07-28T20:13:05Z

First of five stacked PRs replacing #4551, which bundled the whole subagent-observability feature into one ~3,100-line change. Splitting it out so each piece can actually be reviewed; the seams between these pieces are where the bugs were hiding.

Scope: data model, storage, and migration only. Nothing produces the new data yet. Adapters are given neutral defaults so every subagent row stays valid. Populating them for real is 2/5, and reuse semantics are 3/5.

What's here

Contracts gain a reusable subagent identity — per-activation records (SubagentActivationId, OrchestrationV2SubagentActivation), cumulative usage, a role, recent activity, and workflow grouping. A subagent can also now rest at idle between activations.

Migration 044 creates the activation projection table. Legacy rows stay readable through schema defaults and projection replay, so no JSON backfill is required.

The status mapping is the important part

A subagent status is not a turn item status — idle has no timeline equivalent. The two are bridged by an explicit Record<subagent status, turn item status> rather than a copy, which makes the mapping total: adding a subagent status without giving it a timeline meaning is a compile error.

This is not hypothetical. An earlier iteration copied the raw status through, which wrote a turn-item.updated event that its own schema could not decode. Nothing failed at write time — but the projection rebuild runs at startup and died on that stored event, so the server became permanently unbootable with no in-app recovery. Adding idle in this PR immediately trips the new compile error at CodexAdapterV2.ts, which is the guard doing its job.

Notes for review

Envelope attribution change: ProviderEventIngestor no longer replaces an explicit null runId/nodeId with the ambient run. Activations legitimately have no run id. The envelope is persistence metadata only (routing reads payload fields), but this does change stored metadata for existing event types that already pass explicit nulls.
Migration behavior: migration 044 adds activation storage only. Legacy subagent JSON is decoded through schema defaults and projections are rebuilt from events, avoiding a one-off JSON backfill.
A database bricked by the earlier broken build is not repaired by this PR — turn items still correctly reject idle. Only relevant if that build ran anywhere beyond local dev.

Testing

Typecheck clean and lint clean across server, contracts, client-runtime, and web.

server 1,676 passing
contracts 223 passing
client-runtime 481 passing
web 1,498 passing

Also booted a server on a fresh state directory and confirmed migration 044 applies and the app starts.

Reviewed by an independent agent pass before opening; its findings on helper scope and the missing mixed-row migration test are folded in.

Note

Medium Risk
Touches orchestration event persistence, projection schema version (forced rebuild), and envelope attribution for null run/node ids; delegated-task paths now emit activation events. Adapters still use defaults rather than full provider observability, limiting runtime behavior change in this slice.

Overview
Adds a reusable subagent identity model with per-activation records, usage/role/activity/workflow fields on subagents, and a new idle resting status between activations. Contracts introduce SubagentActivationId, OrchestrationV2SubagentActivation, the subagent-activation.updated domain event, and subagentActivations on thread projections—with schema defaults so legacy stored subagent JSON still decodes.

Persistence: migration 045 creates orchestration_v2_projection_subagent_activations (no JSON backfill of existing subagent rows). Projection schema version bumps 2 → 3; rebuild/maintenance clears activation rows and replays from the event log.

Pipeline wiring: ProjectionStore, client-runtime projection, ProviderEventIngestor (maps subagent_activation.updated → domain event), and RunExecutionService routing. ProviderEventIngestor no longer overwrites envelope runId/nodeId when the payload explicitly passes null (needed for detached activations).

Producers (still mostly defaults): provider adapters and tests populate neutral observability defaults on subagent payloads; Codex maps subagent status to turn-item status via orchestrationV2SubagentStatusAsTurnItemStatus ( idle → completed ). Orchestrator emits activation events when app-owned delegated tasks start and when they terminalize. Shared helpers live in SubagentObservability.ts.

A compile-time Record maps every subagent status to a decodable turn-item status so raw idle cannot be copied onto timeline rows and brick projection replay.

^{Reviewed by Cursor Bugbot for commit 9d3c4c6. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Add subagent activation observability data model to orchestration-v2

Introduces OrchestrationV2SubagentActivation as a first-class schema in orchestrationV2.ts, with a new subagent-activation.updated domain event and thread projection field subagentActivations.
Adds new observability fields to OrchestrationV2Subagent: kind, role, usage, currentActivationId, activationCount, workflow, workflowMembership, and recentActivity, all with backward-compatible defaults.
The orchestrator emits subagent-activation.updated events when delegating work (running state) and on termination, tracking activation lifecycle in Orchestrator.ts.
Adds migration 45 (045_OrchestrationV2SubagentObservability.ts) creating the orchestration_v2_projection_subagent_activations table with indexes on (thread_id, subagent_id, ordinal) and (run_id, status).
Projection schema version bumped from 2 to 3; projection rebuilds now clear stale activation rows; all provider adapters (ACP, Claude, Codex, Cursor, OpenCode) populate the new subagent fields with defaults.

^{Macroscope summarized 9d3c4c6.}

coderabbitai · 2026-07-28T20:13:14Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 57f5496a-b420-419d-9957-aadc7566680d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch subagent-obs/01-contracts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Introduces the schema, storage, and migration for richer subagent tracking. Nothing produces the new data yet — adapters populate neutral defaults so every subagent row remains valid — which keeps this change reviewable as a pure data-model step. Contracts gain a reusable subagent identity: per-activation records (SubagentActivationId, OrchestrationV2SubagentActivation), cumulative usage, a role, recent activity, and workflow grouping. A subagent may now also rest at "idle" between activations. Because a subagent status is not a turn item status, the two are bridged by an explicit mapping rather than a copy. The Record type makes that total: adding a subagent status without giving it a timeline meaning is a compile error. Without it, a producer can emit a turn item whose own schema cannot decode it, which is unrecoverable — the projection rebuild then fails on every subsequent startup and the server cannot boot. Migration 043 backfills existing rows so old events stay readable. Its riskiest path is a partially-migrated row, where already-present JSON is round-tripped through COALESCE; a test pins that structured values keep their JSON subtype rather than being rewritten as quoted strings. Also narrows event-envelope attribution in ProviderEventIngestor: a payload carrying an explicit null run or node id now keeps that null instead of inheriting the ambient run. Activations legitimately have no run id, and the envelope is persistence metadata only — routing reads payload fields — but this does change stored metadata for existing event types that already pass explicit nulls.

… backfill Every observability field the migration backfilled carries a decoding default equal to the value it wrote, so pre-upgrade rows already read back correctly without it. The projection schema version bump also fails startup verification, which deletes and replays those rows from the event log before anything reads them. Pin both halves: a contracts test decodes a stored payload missing all eight fields through the schema the projection actually uses, and the migration test asserts an existing row survives byte-identical. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…cope The lint rule the CI Check job enforces flags a compiled decoder rebuilt on every call. The activation payload decoder and the subagent decoders this PR added were inline, which took the branch from the base's 67 lint warnings to 73 and failed the job. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…o stack-01 # Conflicts: # apps/server/src/orchestration-v2/ProviderEventIngestor.test.ts # apps/server/src/persistence/Migrations.ts # apps/server/src/persistence/Migrations/036_037_OrchestrationV2.test.ts

…runs Promoting a queued run rewrote its user_message turn item with inputIntent: "turn_start", clobbering the queued_turn intent the item was created with. Every provider's queued_turn replay fixture failed with [turn_start, turn_start] instead of [turn_start, queued_turn]. Keep the existing item's intent and only default the synthesized fallback, which is queued by definition. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

macroscopeapp · 2026-07-30T20:10:36Z

Approvability

Verdict: Needs human review

New feature adding subagent observability data model with schema changes, new database migration, new event types, and runtime modifications in the orchestrator. The scope and nature of these changes warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

…o stack-01 # Conflicts: # apps/server/src/orchestration-v2/Orchestrator.ts

This was referenced Jul 28, 2026

feat(orchestration-v2): add subagent observability data model (1/5) #4768

Merged

feat(orchestration-v2): populate subagent observability from providers (2/5) #4629

Open

github-actions Bot added vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. size:L 100-499 changed lines (additions + deletions). labels Jul 28, 2026

shivamhwp and others added 4 commits July 30, 2026 05:22

test(mobile): include subagent activations in cached projection

e4f6d13

shivamhwp force-pushed the subagent-obs/01-contracts branch from f4037f3 to e4f6d13 Compare July 30, 2026 00:00

test(orchestration-v2): narrow nullable retry timestamp

c280c08

shivamhwp mentioned this pull request Jul 30, 2026

fix(orchestrator): preserve queued_turn intent when promoting queued runs #5033

Closed

T3 Code Test and others added 3 commits July 31, 2026 01:25

Merge remote-tracking branch 'upstream/t3code/codex-turn-mapping' int…

5338a98

…o stack-01 # Conflicts: # apps/server/src/orchestration-v2/ProviderEventIngestor.test.ts # apps/server/src/persistence/Migrations.ts # apps/server/src/persistence/Migrations/036_037_OrchestrationV2.test.ts

test(persistence): cover renumbered subagent observability migration

6978133

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

shivamhwp marked this pull request as ready for review July 30, 2026 20:04

kakismash mentioned this pull request Jul 30, 2026

[Bug]: Desktop/web thread shows no sign of delegated CLI-agent work: silent while it runs, idle-looking when backgrounded, spontaneous wake after #5043

Open

2 tasks

Merge remote-tracking branch 'upstream/t3code/codex-turn-mapping' int…

9d3c4c6

…o stack-01 # Conflicts: # apps/server/src/orchestration-v2/Orchestrator.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(orchestration-v2): add subagent observability data model (1/5) - #4779

feat(orchestration-v2): add subagent observability data model (1/5)#4779
shivamhwp wants to merge 9 commits into
t3code/codex-turn-mappingfrom
subagent-obs/01-contracts

shivamhwp commented Jul 28, 2026 •

edited by macroscopeapp Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 28, 2026 •

edited

Loading

Review skipped

Uh oh!

macroscopeapp Bot commented Jul 30, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

shivamhwp commented Jul 28, 2026 • edited by macroscopeapp Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's here

The status mapping is the important part

Notes for review

Testing

Add subagent activation observability data model to orchestration-v2

Uh oh!

coderabbitai Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

macroscopeapp Bot commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approvability

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

shivamhwp commented Jul 28, 2026 •

edited by macroscopeapp Bot

Loading

coderabbitai Bot commented Jul 28, 2026 •

edited

Loading

macroscopeapp Bot commented Jul 30, 2026 •

edited

Loading